Rather than get too long-winded here, I'm going to give you example of how I use OptionDialog and use it to explain the parameters and what effect each has on the displayed dialog window. Ready? Here goes...
The following example code produces a dialog that looks like this:
Dim Answer, MsgText as String
Const CR = Chr(13) 'A carriage return.
Answer = "Continue"
If MeterSN <> G_MeterSN Then
ThisPatient = GetPatientName
MsgText = "The serial number of the meter "
MsgText = MsgText + "you are reading does not match "
MsgText = MsgText + "the one recorded for " + ThisPatient + "!" + CR + CR
MsgText = MsgText + "If you continue, you will add the "
MsgText = MsgText + "data just read to " + ThisPatient + "'s history file "
MsgText = MsgText + "and make the current meter the "
MsgText = MsgText + "'meter of record' for " + ThisPatient + "."
The line in red is, of course, the one of interest.
Text
The text size and style, both on the buttons and in the message, are set in the IDE on the control's properties but you can change this if you'd prefer and the sizing should all still work.
Methods
The only method externally available is "Ask" which is a function that returns a string, so we must assign it's result to something. Fortunately, that's why we'd be using OptionDialog anyway. What gets returned to "Answer" is the text (or caption, if you'd prefer) of the button that the user clicks.
Parameters
Message
The first parameter is the text that we want to be displayed to the user. As you can see from the example, we can easily put "paragraph breaks" into our text by adding a couple of carriage returns. The StaticText that displays our message is dynamically resized to make it all fit. Since this is a dialog it is not anticipated that you will pass so much text so as to cause the bottom of the window to be off the screen but, you could so just don't, OK? If you do so, and the buttons are below the bottom of the screen, you'll not be able to dismiss the OptionDialog! Too bad... you've been warned.
The algorithm that figures out the height for the StaticText isn't perfect and it's possible that not all of your text will display, especially when there are few buttons and an icon is displayed. An easy remedy is to add a carriage return or three to the end of your message.
Icon
The second parameter says what icon to display. Passing an empty string will cause OptionDialog to have no icon displayed and the text will extend over the area where the icon would have been. You can put any of the built-in icon names (stop, caution, note) here. You can also specify the ID (still in a string) of your own icon. OptionDialog will look for a cicn resourse with this ID and display it, if it is found. To be found, you should put your cicn into a ResEdit file called "Resources" and drag it into your project. You can find an example of this by digging around in the supplied OptionDialog Test project. If your cicn resource is not found, OptionDialog will display "Oops! No Icon!" in it's place.
Buttons
There's a lot going on here, so pay attention...
The third parameter is a string that contains the text you want on your buttons. You'll get as many buttons as items in this list. You can have a ridiculously large numer of buttons. OptionDialog will widen itself to allow all of them to fit in a single row along the bottom and it doesn't care that it might now be wider than you screen. The buttons are created in the opposite order they appear in the parameter, as you can see in the example. You can also have a ridiculously long button.
A vertical bar "|" is used as a delimiter for the button items. I chose this character because it seems quite unlikely that it would appear on a button. But, Murphy's Law being what it is, you can easily "Find & Replace" it if you need to (OptionDialog is open source, remember?).
There are two special prependages that you can add to a button's text: "C:", to tell OptionDialog that you want this button's Cancel property set, and; "D:", to tell OptionDialog that you want this button's Default property set
If you pass an empty string for this parameter, OptionDialog will create a single button with the text "Error!" so you can dismiss the dialog.
Beep
The last parameter is a boolean that signifies whether or not you want OptionDialog to beep. "True" means to beep.
Test Project
The OptionDialog Test project lets you try out the various combinations available with OptionDialog.
